feat: Add SNMP Monitor by mattv8 · Pull Request #4717 · louislam/uptime-kuma

mattv8 · 2024-04-27T01:18:36Z

Tick the checkbox if you understand [x]:

I have read and understand the pull request rules.

Description (Updated 06 June 2024 to reflect new scope)

This PR introduces a new SNMP monitor type and extends the functionality of JSON query monitoring with additional comparison operators. The following changes have been made:

Uptime Kuma Core

Broke out the JSON query evaluation logic into a new utility function for better reusability and clarity, called evaluateJsonQuery(data: any, jsonPath: string, jsonPathOperator: string, expectedValue: any), which returns { status: boolean, response: any } where status is the UP/DOWN evaluation and response is the result of the JSON query evaluation.

New SNMP Monitor Type:

Added new fields for SNMP configuration, including community string, OID (Object Identifier), and SNMP version.
Updated the database schema to include SNMP-related columns.
Utilizes new evaluateJsonQuery() to determine monitor status based on SNMP values and configured conditions.
Utilizes net-snmp library for SNMP queries.

JSON Query Monitoring:

Utilizes new evaluateJsonQuery() to determine monitor status based on JSON query evaluation and configured conditions.
Extended the UI to allow users to select the desired comparison operator (==, !=, <, <=, >, >=).
Introduced a new property in the monitoring configuration to hold the comparison operator.
Ensured backward compatibility by defaulting to == if the operator is not specified in existing configurations.

Resolves #1675
Resolves #4715
Resolves #4614
Resolves #4617

Type of change

Please delete any options that are not relevant.

New feature (non-breaking change which adds functionality)
This change requires a documentation update

Checklist

My code follows the style guidelines of this project
I ran ESLint and other linters for modified files
I have performed a self-review of my own code and tested it
I have commented my code, particularly in hard-to-understand areas (including JSDoc for methods)
My changes generates no new warnings
My code needed automated testing. I have added them (this is optional task)

Screenshots

This commit introduces a new SNMP monitor feature to the application, allowing users to monitor devices using SNMP (Simple Network Management Protocol).

net-snmp over snmp-native is: -more robust -more popular -better documented -supports v3

Further testing of SNMP feat, however I'm running into the issue `Error in SNMP check: RequestTimedOutError: Request timed out` when the check function is called. I am unsure as to why since my local SNMP script works great with very similar code.

@CommanderStorm

Thanks for pointing it out @CommanderStorm!

DB must allow nulls otherwise this will break other monitors.

knex requires down function

Updates appropriate values async when editing the SNMP monitor

mattv8 · 2024-04-30T21:51:04Z

@CommanderStorm I'm ready for review. It is not passing ES Lint, although when I run npm run lint:prod --fix there are some changes to server/model/monitor.js that are unrelated to this PR. I'm unsure as how to proceed on the linting side of things.

Co-authored-by: Frank Elsinga <frank@elsinga.de>

https://github.com/louislam/uptime-kuma/pull/4717/files/b4bd003626986be1faab7142710f9443273d89fc#r1585590243

Co-Authored-By: Frank Elsinga <frank.elsinga@tum.de>

Revert change from "Hostname" to "Hostname or IP Address" from efb1642

src/util.ts

mattv8 · 2024-06-14T22:44:09Z

Just to be absolutely sure this feat is ready to ship from my perspective, I tested many scenarios for both the SNMP and JSON Query monitor types. I tested various edge cases and went through each condition (==, !=, <, <=, >, >=). I evaluated every conceivable SNMP response type available from my device (OctetString, OID, TimeTicks, Integer, Gauge, Counter, IpAddress, Counter64), and several JSON response types from my server (object, array, string, integer, float and bool). I am pushing one last commit to round up the additional edge cases I discovered, and now these cases seem to be managed gracefully. While I acknowledge my testing is not comprehensive, I feel confident that the feature now handles most (if not all) expected scenarios.

In the spoiler below is a table with most of the scenarios, and how the console displays the UP/DOWN status:

Details

Name	Status	DateTime	Message
SNMP	Up	6/14/2024 12:31	JSON query passes (comparing �1C4� != 0)
SNMP	Down	6/14/2024 12:31	Error evaluating JSON query: The left side of the "%" operator must evaluate to a number. Response from server was: �1C!�
SNMP	Up	6/14/2024 12:29	JSON query passes (comparing 0 == 0)
SNMP	Down	6/14/2024 12:24	JSON query does not pass (comparing NaN contains 1)
SNMP	Up	6/14/2024 12:24	JSON query passes (comparing 1.2 contains 1)
SNMP	Down	6/14/2024 12:23	JSON query does not pass (comparing 1.2 == 1)
SNMP	Up	6/14/2024 12:23	JSON query passes (comparing vlanVoice == vlanVoice)
SNMP	Down	6/14/2024 12:23	JSON query does not pass (comparing vlanVoice == vlanVoice!)
SNMP	Up	6/14/2024 12:23	JSON query passes (comparing vlanVoice contains vlan)
SNMP	Down	6/14/2024 12:23	JSON query does not pass (comparing vlanVoice contains `)
SNMP	Up	6/14/2024 12:22	JSON query passes (comparing `==`)
SNMP	Down	6/14/2024 12:22	JSON query does not pass (comparing ` == 0)
SNMP	Up	6/14/2024 12:22	JSON query passes (comparing -1 contains -)
SNMP	Down	6/14/2024 12:22	JSON query does not pass (comparing -1 == 1)
SNMP	Up	6/14/2024 12:21	JSON query passes (comparing -1 < 1)
SNMP	Down	6/14/2024 12:21	JSON query does not pass (comparing `�� contains 1)
SNMP	Up	6/14/2024 12:20	JSON query passes (comparing `�� != 1)
SNMP	Down	6/14/2024 12:20	Error evaluating JSON query: Unable to cast value to a number: "0.0.0.0". Response from server was: 0.0.0.0
SNMP	Up	6/14/2024 12:20	JSON query passes (comparing 0.0.0.0 == 0.0.0.0)
SNMP	Down	6/14/2024 12:18	Error evaluating JSON query: The literal value 0 cannot be used as a step within a path expression. Response from server was: 0.0.0.0
SNMP	Up	6/14/2024 12:17	JSON query passes (comparing 0.0.0.0 == 0.0.0.0)
SNMP	Down	6/14/2024 12:17	JSON query does not pass (comparing 0.0.0.0 == 1)
SNMP	Up	6/14/2024 12:17	JSON query passes (comparing 1 == 1)
SNMP	Down	6/14/2024 12:17	JSON query does not pass (comparing 1 == true)
SNMP	Up	6/14/2024 12:17	JSON query passes (comparing 1 == 1)
SNMP	Down	6/14/2024 12:17	JSON query does not pass (comparing 1 contains two)
SNMP	Up	6/14/2024 12:16	JSON query passes (comparing 1 > 0)
SNMP	Down	6/14/2024 12:16	JSON query does not pass (comparing 1 < 0)
SNMP	Up	6/14/2024 12:16	JSON query passes (comparing 1 != 0)
SNMP	Down	6/14/2024 12:16	JSON query does not pass (comparing 1 contains 0)
SNMP	Up	6/14/2024 12:16	JSON query passes (comparing 0 contains 0)
SNMP	Down	6/14/2024 12:16	JSON query does not pass (comparing 0 contains 1)
SNMP	Up	6/14/2024 12:16	JSON query passes (comparing 0 <= 1)
SNMP	Down	6/14/2024 12:15	JSON query does not pass (comparing 0 != 0)
SNMP	Up	6/14/2024 12:15	JSON query passes (comparing 0 == 0)
JSON	Down	6/14/2024 16:14	Error evaluating JSON query: Expected "]" before end of expression. Response from server was: {"success":true,"data":["2023-08-10","2023-08-23",… (truncated)
JSON	Up	6/14/2024 16:14	JSON query passes (comparing 2023-08-10 contains 2023)
JSON	Down	6/14/2024 16:14	Error evaluating JSON query: The post-JSON query evaluated response from the server is of type object, which cannot be directly compared to the expected value. Response from server was: ["2023-08-10","2023-08-23","2023-08-24","2023-09-0… (truncated)
JSON	Up	6/14/2024 16:14	JSON query passes (comparing 2023-08-10 contains 2023)
JSON	Down	6/14/2024 16:11	Error evaluating JSON query: The post-JSON query evaluated response from the server is of type object, which cannot be directly compared to the expected value. Response from server was: {"value":"12"}
JSON	Up	6/14/2024 16:11	JSON query passes (comparing 12 == 12)
JSON	Down	6/14/2024 16:11	Error evaluating JSON query: Unexpected end of expression. Response from server was: {"data":{"EventId":{"value":"12"},"SiteId":{"value… (truncated)
JSON	Up	6/14/2024 16:10	JSON query passes (comparing 12 == 12)
JSON	Down	6/14/2024 16:10	JSON query does not pass (comparing 12 == 13)
JSON	Up	6/14/2024 16:10	JSON query passes (comparing 12 >= 12)
JSON	Down	6/14/2024 16:10	JSON query does not pass (comparing 12 >= 13)
JSON	Up	6/14/2024 16:10	JSON query passes (comparing 12 == 12)
JSON	Down	6/14/2024 16:10	JSON query does not pass (comparing true == 1)
JSON	Up	6/14/2024 16:09	JSON query passes (comparing true contains t)
JSON	Down	6/14/2024 16:09	Error evaluating JSON query: Empty or undefined response. Check query syntax and response structure.. Response from server was: undefined
JSON	Up	6/14/2024 16:09	JSON query passes (comparing true == true)
JSON	Down	6/14/2024 16:09	Error evaluating JSON query: Empty or undefined response. Check query syntax and response structure.. Response from server was: undefined
JSON	Up	6/14/2024 16:09	JSON query passes (comparing true == true)

mattv8 · 2024-06-28T15:02:11Z

Hey @chakflying wondering if you'd be willing to take a look at this again?

hanunes · 2024-07-14T12:01:15Z

Any news on this? Really looking forward to it. 😄

mattv8 · 2024-07-14T14:07:52Z

Any news on this? Really looking forward to it. 😄

No news yet but if you're able to help test I would appreciate it. You can spin up your own Docker instance of this PR with

docker run --rm -it -p 3000:3000 -p 3001:3001 --pull always -e 'UPTIME_KUMA_GH_REPO=mattv8:snmp-monitor' louislam/uptime-kuma:pr-test2

hanunes · 2024-07-14T17:22:28Z

When I try to deploy it, it gives an error. Where it says is has no access to /data/upload. Do you know what that means? If I don't setup a persistent directory on /app/data, the database-setup page stays blank. Could just be me being dumb, but I don't understand what's going on. 😅

chakflying

Tested working, I'm okay with this. Great work.

Not familiar with this at all but I'm guessing more work will be required if we want to support table data in future?

mattv8 · 2024-07-15T17:29:33Z

I'm guessing more work will be required if we want to support table data in future?

It would be simple enough to return the raw SNMP value from async check(monitor, heartbeat, _server) for display in a table (assuming this is what you mean). Likewise for evaluateJsonQuery, which is already returning the response. So, yes, a bit more work would be required.

Can you reference a PR so I can better understand what you mean by "table data"?

CommanderStorm · 2024-07-15T19:57:41Z

Thanks for the new monitor! 🎉

Note

This PR is part of the v2.0 merge window => see #4500 for the bugs that need to be addressed before we can ship this release ^^

_{All changes in this PR are small and uncontroversial ⇒ merging with junior maintainer approval}

src/util.js

hanunes · 2024-07-17T18:13:02Z

@mattv8, how can I test this? Will it only be released with v2?

mattv8 · 2024-07-17T18:36:19Z

Try this:

git clone https://github.com/louislam/uptime-kuma.git # Assuming you have git installed

cd uptime-kuma # Change into the directory you just cloned

git fetch origin pull/4717/head:pr-4717 && git checkout pr-4717 # Check out this PR

npm ci # Assuming you have node and npm installed

npm run dev # This will start the server on http://localhost:3000

wglenn01 · 2024-07-17T22:02:51Z

@mattv8 Hey how can I try this release with SNMP support if i'm already running v 1.23.13?

CommanderStorm · 2024-07-17T22:27:56Z

V2.0 is currently not released. Please see #4500 for further details on the bugs that need fixing.

louislam · 2025-11-27T11:20:54Z

src/util.js

+            throw new Error("Empty or undefined response. Check query syntax and response structure");
+        }
+        if (typeof response === "object" || response instanceof Date || typeof response === "function") {
+            throw new Error(`The post-JSON query evaluated response from the server is of type ${typeof response}, which cannot be directly compared to the expected value`);


Hi @mattv8 evaluateJsonQuery() doesn't seem to be working for json query monitor.

It runs into this line, could you look into this, thanks.

Bug report: #6277

SNMP Initial Commits

d92003e

This commit introduces a new SNMP monitor feature to the application, allowing users to monitor devices using SNMP (Simple Network Management Protocol).

mattv8 mentioned this pull request Apr 27, 2024

SNMP Value Retrieval #1675

Closed

1 task

mattv8 changed the title ~~feat: Add SNMP Monitor~~ feat: Add SNMP Monitor (WIP) Apr 27, 2024

mattv8 added 3 commits April 29, 2024 13:58

Use net-snmp instead of snmp-native

a3cdd69

net-snmp over snmp-native is: -more robust -more popular -better documented -supports v3

Updated a comment

ff5890a

Further SNMP monitor development

4a882be

Further testing of SNMP feat, however I'm running into the issue `Error in SNMP check: RequestTimedOutError: Request timed out` when the check function is called. I am unsure as to why since my local SNMP script works great with very similar code.

This comment has been minimized.

Sign in to view

Wrong variable used

99dc4cf

Thanks for pointing it out @CommanderStorm!

This comment was marked as resolved.

Sign in to view

mattv8 added 6 commits April 30, 2024 15:10

Update db migration: allow nulls

138075a

DB must allow nulls otherwise this will break other monitors.

Update db migration: down function

9c8024c

knex requires down function

Update bean model backend

9d28fcf

Updates appropriate values async when editing the SNMP monitor

Frontend input validation

4593afb

Minor frontend styling

9848ce4

Finalized SNMP monitor

704ffd3

mattv8 changed the title ~~feat: Add SNMP Monitor (WIP)~~ feat: Add SNMP Monitor Apr 30, 2024

mattv8 marked this pull request as ready for review April 30, 2024 21:46

Merge branch 'master' into snmp-monitor

b4bd003

This comment was marked as resolved.

Sign in to view

mattv8 and others added 6 commits April 30, 2024 17:54

Apply suggestions from code review

ba47aca

Co-authored-by: Frank Elsinga <frank@elsinga.de>

ES Lint Compliant

7459654

Corrected down function

e944492

https://github.com/louislam/uptime-kuma/pull/4717/files/b4bd003626986be1faab7142710f9443273d89fc#r1585590243

ES Lint Compliant

97a9094

Remove supurfluous log.debug

9ba0f68

Co-Authored-By: Frank Elsinga <frank.elsinga@tum.de>

Delete .EditMonitor.vue.swp

ba84f01

Co-Authored-By: Frank Elsinga <frank.elsinga@tum.de>

"Hostname or IP Address" back to "Hostname"

e237d66

Revert change from "Hostname" to "Hostname or IP Address" from efb1642

mattv8 commented Jun 14, 2024

View reviewed changes

src/util.ts Outdated Show resolved Hide resolved

mattv8 added 2 commits June 14, 2024 16:44

C&P typo from review

a037448

Robustness and edge-case handling

8d8ce23

github-actions bot added the pr:please resolve merge conflict A merge-conflict needs to be addressed before reviewing makes sense again label Jun 17, 2024

chakflying approved these changes Jul 15, 2024

View reviewed changes

Merge branch 'master' into snmp-monitor

71f9384

github-actions bot removed the pr:please resolve merge conflict A merge-conflict needs to be addressed before reviewing makes sense again label Jul 15, 2024

CommanderStorm reviewed Jul 15, 2024

View reviewed changes

src/util.js Show resolved Hide resolved

fixed merge-typo

c82de20

CommanderStorm merged commit 4aef678 into louislam:master Jul 15, 2024

CommanderStorm added this to the 2.0.0 milestone Aug 24, 2024

louislam mentioned this pull request Aug 31, 2024

Weblate no longer adds the latest committed translations #5070

Closed

1 task

FoxxMD mentioned this pull request Oct 1, 2024

Adding NUT (Network UPS Tools) Monitor Type #3932

Open

1 task

plegrand1 mentioned this pull request Oct 25, 2024

V2 SNMP #5247

Closed

ntz-waldi mentioned this pull request Jun 10, 2025

Full SNMP integration with Autodetection of Monitorable Points #5899

Open

louislam mentioned this pull request Nov 27, 2025

JSON query mismatch between v1 and v2. jsonata.org not fully supported #6277

Closed

louislam reviewed Nov 27, 2025

View reviewed changes

CommanderStorm removed the pr:needs review this PR needs a review by maintainers or other community members label Jan 11, 2026

Uh oh!

Conversation

mattv8 commented Apr 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description (Updated 06 June 2024 to reflect new scope)

Type of change

Checklist

Screenshots

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

mattv8 commented Apr 30, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

mattv8 commented Jun 14, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mattv8 commented Jun 28, 2024

Uh oh!

hanunes commented Jul 14, 2024

Uh oh!

mattv8 commented Jul 14, 2024

Uh oh!

hanunes commented Jul 14, 2024

Uh oh!

chakflying left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattv8 commented Jul 15, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CommanderStorm commented Jul 15, 2024

Uh oh!

Uh oh!

hanunes commented Jul 17, 2024

Uh oh!

mattv8 commented Jul 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wglenn01 commented Jul 17, 2024

Uh oh!

CommanderStorm commented Jul 17, 2024

Uh oh!

louislam Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

mattv8 Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mattv8 commented Apr 27, 2024 •

edited

Loading

mattv8 commented Apr 30, 2024 •

edited

Loading

mattv8 commented Jun 14, 2024 •

edited

Loading

chakflying left a comment •

edited

Loading

mattv8 commented Jul 15, 2024 •

edited

Loading

mattv8 commented Jul 17, 2024 •

edited

Loading